{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#| default_exp models.lstm"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#| hide\n",
    "%load_ext autoreload\n",
    "%autoreload 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# LSTM"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Long Short-Term Memory Recurrent Neural Network (`LSTM`), uses a multilayer `LSTM` encoder and an `MLP` decoder. It builds upon the LSTM-cell that improves the exploding and vanishing gradients of classic `RNN`'s. This network has been extensively used in sequential prediction tasks like language modeling, phonetic labeling, and forecasting. The predictions are obtained by transforming the hidden states into contexts $\\mathbf{c}_{[t+1:t+H]}$, that are decoded and adapted into $\\mathbf{\\hat{y}}_{[t+1:t+H],[q]}$ through MLPs.\n",
    "\n",
    "\\begin{align}\n",
    " \\mathbf{h}_{t} &= \\textrm{LSTM}([\\mathbf{y}_{t},\\mathbf{x}^{(h)}_{t},\\mathbf{x}^{(s)}], \\mathbf{h}_{t-1})\\\\\n",
    "\\mathbf{c}_{[t+1:t+H]}&=\\textrm{Linear}([\\mathbf{h}_{t}, \\mathbf{x}^{(f)}_{[:t+H]}]) \\\\ \n",
    "\\hat{y}_{\\tau,[q]}&=\\textrm{MLP}([\\mathbf{c}_{\\tau},\\mathbf{x}^{(f)}_{\\tau}])\n",
    "\\end{align}\n",
    "\n",
    "where $\\mathbf{h}_{t}$, is the hidden state for time $t$, $\\mathbf{y}_{t}$ is the input at time $t$ and $\\mathbf{h}_{t-1}$ is the hidden state of the previous layer at $t-1$, $\\mathbf{x}^{(s)}$ are static exogenous inputs, $\\mathbf{x}^{(h)}_{t}$ historic exogenous, $\\mathbf{x}^{(f)}_{[:t+H]}$ are future exogenous available at the time of the prediction.\n",
    "\n",
    "**References**<br>-[Jeffrey L. Elman (1990). \"Finding Structure in Time\".](https://onlinelibrary.wiley.com/doi/abs/10.1207/s15516709cog1402_1)<br>-[Haşim Sak, Andrew Senior, Françoise Beaufays (2014). \"Long Short-Term Memory Based Recurrent Neural Network Architectures for Large Vocabulary Speech Recognition.\"](https://arxiv.org/abs/1402.1128)<br>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Figure 1. Long Short-Term Memory Cell.](imgs_models/lstm.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#| hide\n",
    "import logging\n",
    "from fastcore.test import test_eq\n",
    "from nbdev.showdoc import show_doc\n",
    "from neuralforecast.common._model_checks import check_model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "from typing import Optional\n",
    "\n",
    "import torch\n",
    "import torch.nn as nn\n",
    "import warnings\n",
    "\n",
    "from neuralforecast.losses.pytorch import MAE\n",
    "from neuralforecast.common._base_model import BaseModel\n",
    "from neuralforecast.common._modules import MLP"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "class LSTM(BaseModel):\n",
    "    \"\"\" LSTM\n",
    "\n",
    "    LSTM encoder, with MLP decoder.\n",
    "    The network has `tanh` or `relu` non-linearities, it is trained using \n",
    "    ADAM stochastic gradient descent. The network accepts static, historic \n",
    "    and future exogenous data.\n",
    "\n",
    "    **Parameters:**<br>\n",
    "    `h`: int, forecast horizon.<br>\n",
    "    `input_size`: int, maximum sequence length for truncated train backpropagation. Default -1 uses 3 * horizon <br>\n",
    "    `inference_input_size`: int, maximum sequence length for truncated inference. Default None uses input_size history.<br>\n",
    "    `h_train`: int, maximum sequence length for truncated train backpropagation. Default 1.<br>\n",
    "    `encoder_n_layers`: int=2, number of layers for the LSTM.<br>\n",
    "    `encoder_hidden_size`: int=200, units for the LSTM's hidden state size.<br>\n",
    "    `encoder_bias`: bool=True, whether or not to use biases b_ih, b_hh within LSTM units.<br>\n",
    "    `encoder_dropout`: float=0., dropout regularization applied to LSTM outputs.<br>\n",
    "    `context_size`: deprecated.<br>\n",
    "    `decoder_hidden_size`: int=200, size of hidden layer for the MLP decoder.<br>\n",
    "    `decoder_layers`: int=2, number of layers for the MLP decoder.<br>\n",
    "    `futr_exog_list`: str list, future exogenous columns.<br>\n",
    "    `hist_exog_list`: str list, historic exogenous columns.<br>\n",
    "    `stat_exog_list`: str list, static exogenous columns.<br>\n",
    "    `exclude_insample_y`: bool=False, whether to exclude the target variable from the input.<br>\n",
    "    `recurrent`: bool=False, whether to produce forecasts recursively (True) or direct (False).<br>\n",
    "    `loss`: PyTorch module, instantiated train loss class from [losses collection](https://nixtla.github.io/neuralforecast/losses.pytorch.html).<br>\n",
    "    `valid_loss`: PyTorch module=`loss`, instantiated valid loss class from [losses collection](https://nixtla.github.io/neuralforecast/losses.pytorch.html).<br>\n",
    "    `max_steps`: int=1000, maximum number of training steps.<br>\n",
    "    `learning_rate`: float=1e-3, Learning rate between (0, 1).<br>\n",
    "    `num_lr_decays`: int=-1, Number of learning rate decays, evenly distributed across max_steps.<br>\n",
    "    `early_stop_patience_steps`: int=-1, Number of validation iterations before early stopping.<br>\n",
    "    `val_check_steps`: int=100, Number of training steps between every validation loss check.<br>\n",
    "    `batch_size`: int=32, number of differentseries in each batch.<br>\n",
    "    `valid_batch_size`: int=None, number of different series in each validation and test batch.<br>\n",
    "    `windows_batch_size`: int=128, number of windows to sample in each training batch, default uses all.<br>\n",
    "    `inference_windows_batch_size`: int=1024, number of windows to sample in each inference batch, -1 uses all.<br>\n",
    "    `start_padding_enabled`: bool=False, if True, the model will pad the time series with zeros at the beginning, by input size.<br>\n",
    "    `step_size`: int=1, step size between each window of temporal data.<br>    \n",
    "    `scaler_type`: str='robust', type of scaler for temporal inputs normalization see [temporal scalers](https://nixtla.github.io/neuralforecast/common.scalers.html).<br>\n",
    "    `random_seed`: int=1, random_seed for pytorch initializer and numpy generators.<br>\n",
    "    `drop_last_loader`: bool=False, if True `TimeSeriesDataLoader` drops last non-full batch.<br>\n",
    "    `alias`: str, optional,  Custom name of the model.<br>\n",
    "    `optimizer`: Subclass of 'torch.optim.Optimizer', optional, user specified optimizer instead of the default choice (Adam).<br>\n",
    "    `optimizer_kwargs`: dict, optional, list of parameters used by the user specified `optimizer`.<br>\n",
    "    `lr_scheduler`: Subclass of 'torch.optim.lr_scheduler.LRScheduler', optional, user specified lr_scheduler instead of the default choice (StepLR).<br>\n",
    "    `lr_scheduler_kwargs`: dict, optional, list of parameters used by the user specified `lr_scheduler`.<br>    \n",
    "    `dataloader_kwargs`: dict, optional, list of parameters passed into the PyTorch Lightning dataloader by the `TimeSeriesDataLoader`. <br>\n",
    "    `**trainer_kwargs`: int,  keyword trainer arguments inherited from [PyTorch Lighning's trainer](https://pytorch-lightning.readthedocs.io/en/stable/api/pytorch_lightning.trainer.trainer.Trainer.html?highlight=trainer).<br>    \n",
    "    \"\"\"\n",
    "    # Class attributes\n",
    "    EXOGENOUS_FUTR = True\n",
    "    EXOGENOUS_HIST = True\n",
    "    EXOGENOUS_STAT = True\n",
    "    MULTIVARIATE = False    # If the model produces multivariate forecasts (True) or univariate (False)\n",
    "    RECURRENT = True        # If the model produces forecasts recursively (True) or direct (False)\n",
    "\n",
    "    def __init__(self,\n",
    "                 h: int,\n",
    "                 input_size: int = -1,\n",
    "                 inference_input_size: Optional[int] = None,\n",
    "                 h_train: int = 1,\n",
    "                 encoder_n_layers: int = 2,\n",
    "                 encoder_hidden_size: int = 128,\n",
    "                 encoder_bias: bool = True,\n",
    "                 encoder_dropout: float = 0.,\n",
    "                 context_size: Optional[int] = None,\n",
    "                 decoder_hidden_size: int = 128,\n",
    "                 decoder_layers: int = 2,\n",
    "                 futr_exog_list = None,\n",
    "                 hist_exog_list = None,\n",
    "                 stat_exog_list = None,\n",
    "                 exclude_insample_y = False,\n",
    "                 recurrent = False,\n",
    "                 loss = MAE(),\n",
    "                 valid_loss = None,\n",
    "                 max_steps: int = 1000,\n",
    "                 learning_rate: float = 1e-3,\n",
    "                 num_lr_decays: int = -1,\n",
    "                 early_stop_patience_steps: int =-1,\n",
    "                 val_check_steps: int = 100,\n",
    "                 batch_size = 32,\n",
    "                 valid_batch_size: Optional[int] = None,\n",
    "                 windows_batch_size = 128,\n",
    "                 inference_windows_batch_size = 1024,\n",
    "                 start_padding_enabled = False,\n",
    "                 step_size: int = 1,\n",
    "                 scaler_type: str = 'robust',\n",
    "                 random_seed = 1,\n",
    "                 drop_last_loader = False,\n",
    "                 alias: Optional[str] = None,\n",
    "                 optimizer = None,\n",
    "                 optimizer_kwargs = None,\n",
    "                 lr_scheduler = None,\n",
    "                 lr_scheduler_kwargs = None,\n",
    "                 dataloader_kwargs = None,\n",
    "                 **trainer_kwargs):\n",
    "        \n",
    "        self.RECURRENT = recurrent\n",
    "        \n",
    "        super(LSTM, self).__init__(\n",
    "            h=h,\n",
    "            input_size=input_size,\n",
    "            inference_input_size=inference_input_size,\n",
    "            h_train=h_train,\n",
    "            futr_exog_list=futr_exog_list,\n",
    "            hist_exog_list=hist_exog_list,\n",
    "            stat_exog_list=stat_exog_list,\n",
    "            exclude_insample_y = exclude_insample_y,\n",
    "            loss=loss,\n",
    "            valid_loss=valid_loss,\n",
    "            max_steps=max_steps,\n",
    "            learning_rate=learning_rate,\n",
    "            num_lr_decays=num_lr_decays,\n",
    "            early_stop_patience_steps=early_stop_patience_steps,\n",
    "            val_check_steps=val_check_steps,\n",
    "            batch_size=batch_size,\n",
    "            valid_batch_size=valid_batch_size,\n",
    "            windows_batch_size=windows_batch_size,\n",
    "            inference_windows_batch_size=inference_windows_batch_size,\n",
    "            start_padding_enabled=start_padding_enabled,\n",
    "            step_size=step_size,\n",
    "            scaler_type=scaler_type,\n",
    "            random_seed=random_seed,\n",
    "            drop_last_loader=drop_last_loader,\n",
    "            alias=alias,\n",
    "            optimizer=optimizer,\n",
    "            optimizer_kwargs=optimizer_kwargs,\n",
    "            lr_scheduler=lr_scheduler,\n",
    "            lr_scheduler_kwargs=lr_scheduler_kwargs,\n",
    "            dataloader_kwargs=dataloader_kwargs,\n",
    "            **trainer_kwargs\n",
    "        )\n",
    "\n",
    "        # LSTM\n",
    "        self.encoder_n_layers = encoder_n_layers\n",
    "        self.encoder_hidden_size = encoder_hidden_size\n",
    "        self.encoder_bias = encoder_bias\n",
    "        self.encoder_dropout = encoder_dropout\n",
    "        \n",
    "        # Context adapter\n",
    "        if context_size is not None:\n",
    "            warnings.warn(\"context_size is deprecated and will be removed in future versions.\")\n",
    "\n",
    "        # MLP decoder\n",
    "        self.decoder_hidden_size = decoder_hidden_size\n",
    "        self.decoder_layers = decoder_layers\n",
    "\n",
    "        # LSTM input size (1 for target variable y)\n",
    "        input_encoder = 1 + self.hist_exog_size + self.stat_exog_size + self.futr_exog_size\n",
    "\n",
    "        # Instantiate model\n",
    "        self.rnn_state = None\n",
    "        self.maintain_state = False\n",
    "        self.hist_encoder = nn.LSTM(input_size=input_encoder,\n",
    "                                    hidden_size=self.encoder_hidden_size,\n",
    "                                    num_layers=self.encoder_n_layers,\n",
    "                                    bias=self.encoder_bias,\n",
    "                                    dropout=self.encoder_dropout,\n",
    "                                    batch_first=True,\n",
    "                                    proj_size=self.loss.outputsize_multiplier if self.RECURRENT else 0)\n",
    "\n",
    "        # Decoder MLP\n",
    "        if not self.RECURRENT:\n",
    "            self.mlp_decoder = MLP(in_features=self.encoder_hidden_size + self.futr_exog_size,\n",
    "                                out_features=self.loss.outputsize_multiplier,\n",
    "                                hidden_size=self.decoder_hidden_size,\n",
    "                                num_layers=self.decoder_layers,\n",
    "                                activation='ReLU',\n",
    "                                dropout=0.0)\n",
    "            if self.h > self.input_size:\n",
    "                self.upsample_sequence = nn.Linear(self.input_size, self.h)            \n",
    "\n",
    "    def forward(self, windows_batch):\n",
    "        \n",
    "        # Parse windows_batch\n",
    "        encoder_input = windows_batch['insample_y']                         # [B, seq_len, 1]\n",
    "        futr_exog     = windows_batch['futr_exog']                          # [B, seq_len, F]\n",
    "        hist_exog     = windows_batch['hist_exog']                          # [B, seq_len, X]\n",
    "        stat_exog     = windows_batch['stat_exog']                          # [B, S]\n",
    "\n",
    "        # Concatenate y, historic and static inputs              \n",
    "        batch_size, seq_len = encoder_input.shape[:2]\n",
    "        if self.hist_exog_size > 0:\n",
    "            encoder_input = torch.cat((encoder_input, hist_exog), dim=2)    # [B, seq_len, 1] + [B, seq_len, X] -> [B, seq_len, 1 + X]\n",
    "\n",
    "        if self.stat_exog_size > 0:\n",
    "            # print(encoder_input.shape)\n",
    "            stat_exog = stat_exog.unsqueeze(1).repeat(1, seq_len, 1)        # [B, S] -> [B, seq_len, S]\n",
    "            encoder_input = torch.cat((encoder_input, stat_exog), dim=2)    # [B, seq_len, 1 + X] + [B, seq_len, S] -> [B, seq_len, 1 + X + S]\n",
    "\n",
    "        if self.futr_exog_size > 0:\n",
    "            encoder_input = torch.cat((encoder_input, \n",
    "                                       futr_exog[:, :seq_len]), dim=2)      # [B, seq_len, 1 + X + S] + [B, seq_len, F] -> [B, seq_len, 1 + X + S + F]\n",
    "\n",
    "        if self.RECURRENT:\n",
    "            if self.maintain_state:\n",
    "                rnn_state = self.rnn_state\n",
    "            else:\n",
    "                rnn_state = None\n",
    "            \n",
    "            output, rnn_state = self.hist_encoder(encoder_input, \n",
    "                                                            rnn_state)      # [B, seq_len, n_output]\n",
    "            if self.maintain_state:\n",
    "                self.rnn_state = rnn_state\n",
    "        else:\n",
    "            hidden_state, _ = self.hist_encoder(encoder_input, None)       # [B, seq_len, rnn_hidden_state]\n",
    "            if self.h > self.input_size:\n",
    "                hidden_state = hidden_state.permute(0, 2, 1)               # [B, seq_len, rnn_hidden_state] -> [B, rnn_hidden_state, seq_len]\n",
    "                hidden_state = self.upsample_sequence(hidden_state)        # [B, rnn_hidden_state, seq_len] -> [B, rnn_hidden_state, h]\n",
    "                hidden_state = hidden_state.permute(0, 2, 1)               # [B, rnn_hidden_state, h] -> [B, h, rnn_hidden_state]\n",
    "            else:\n",
    "                hidden_state = hidden_state[:, -self.h:]                   # [B, seq_len, rnn_hidden_state] -> [B, h, rnn_hidden_state]\n",
    "            \n",
    "            if self.futr_exog_size > 0:\n",
    "                futr_exog_futr = futr_exog[:, -self.h:]                    # [B, h, F]\n",
    "                hidden_state = torch.cat((hidden_state, \n",
    "                                          futr_exog_futr), dim=-1)         # [B, h, rnn_hidden_state] + [B, h, F] -> [B, h, rnn_hidden_state + F]\n",
    "\n",
    "            output = self.mlp_decoder(hidden_state)                        # [B, h, rnn_hidden_state + F] -> [B, seq_len, n_output]\n",
    "\n",
    "        return output[:, -self.h:]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "show_doc(LSTM)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "show_doc(LSTM.fit, name='LSTM.fit')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "show_doc(LSTM.predict, name='LSTM.predict')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#| hide\n",
    "# Unit tests for models\n",
    "logging.getLogger(\"pytorch_lightning\").setLevel(logging.ERROR)\n",
    "logging.getLogger(\"lightning_fabric\").setLevel(logging.ERROR)\n",
    "with warnings.catch_warnings():\n",
    "    warnings.simplefilter(\"ignore\")\n",
    "    check_model(LSTM, [\"airpassengers\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Usage Example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#| eval: false\n",
    "import pandas as pd\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "from neuralforecast import NeuralForecast\n",
    "from neuralforecast.models import LSTM\n",
    "from neuralforecast.losses.pytorch import DistributionLoss\n",
    "from neuralforecast.utils import AirPassengersPanel, AirPassengersStatic\n",
    "\n",
    "Y_train_df = AirPassengersPanel[AirPassengersPanel.ds<AirPassengersPanel['ds'].values[-12]] # 132 train\n",
    "Y_test_df = AirPassengersPanel[AirPassengersPanel.ds>=AirPassengersPanel['ds'].values[-12]].reset_index(drop=True) # 12 test\n",
    "\n",
    "nf = NeuralForecast(\n",
    "    models=[LSTM(h=12, \n",
    "                 input_size=8,\n",
    "                 loss=DistributionLoss(distribution=\"Normal\", level=[80, 90]),\n",
    "                 scaler_type='robust',\n",
    "                 encoder_n_layers=2,\n",
    "                 encoder_hidden_size=128,\n",
    "                 decoder_hidden_size=128,\n",
    "                 decoder_layers=2,\n",
    "                 max_steps=200,\n",
    "                 futr_exog_list=['y_[lag12]'],\n",
    "                 stat_exog_list=['airline1'],\n",
    "                 recurrent=True,\n",
    "                 h_train=1,\n",
    "                 )\n",
    "    ],\n",
    "    freq='ME'\n",
    ")\n",
    "nf.fit(df=Y_train_df, static_df=AirPassengersStatic)\n",
    "Y_hat_df = nf.predict(futr_df=Y_test_df)\n",
    "\n",
    "# Plots\n",
    "Y_hat_df = Y_hat_df.reset_index(drop=False).drop(columns=['unique_id','ds'])\n",
    "plot_df = pd.concat([Y_test_df, Y_hat_df], axis=1)\n",
    "plot_df = pd.concat([Y_train_df, plot_df])\n",
    "\n",
    "plot_df = plot_df[plot_df.unique_id=='Airline1'].drop('unique_id', axis=1)\n",
    "plt.plot(plot_df['ds'], plot_df['y'], c='black', label='True')\n",
    "plt.plot(plot_df['ds'], plot_df['LSTM-median'], c='blue', label='median')\n",
    "plt.fill_between(x=plot_df['ds'][-12:], \n",
    "                 y1=plot_df['LSTM-lo-90'][-12:].values,\n",
    "                 y2=plot_df['LSTM-hi-90'][-12:].values,\n",
    "                 alpha=0.4, label='level 90')\n",
    "plt.grid()\n",
    "plt.plot()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "python3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
